6장. 클로드 코드에 바깥 세상 연결하기

출처: 『혼자 공부하는 바이브 코딩 with 클로드 코드』(조태호) | 예제 코드: github.com/taehojo/vibecoding

코드는 분위기만 — API, 엔드포인트, localStorage 같은 말은 몰라도 됩니다. 표의 '비유'와 '위험'만 봐도 충분해요.

지금까지는 클로드 코드 혼자 만드는 것만 했다.

이 장은 내 앱을 바깥 서비스와 잇는 법을 배운다.

바깥 서비스란 구글의 이미지 인식, 챗봇의 글쓰기 같은 남이 만들어 둔 똑똑한 기능이다.

그 기능을 빌려 와, 냉장고 사진을 찍으면 레시피를 골라 주는 앱을 끝까지 만든다.

0. 이 장의 새 단어 (0장에 없는 것만 3개)

0장 용어집에 있는 말(바이브 코딩·프롬프트·LLM·PRD·localhost 등)은 다 안다고 보고 간다.

이 장에서 처음 나오는 말은 딱 3개다. 먼저 풀어 둔다.

API(에이피아이)

한 문장 뜻 — 내 앱이 바깥 서비스에게 일을 부탁하고 결과를 받는 정해진 창구.

일상비유 — 식당의 웨이터. 손님은 주방에 직접 못 들어간다. 웨이터에게 "파스타요" 하면, 웨이터가 주방에 전하고 음식을 가져온다.

한 줄 예 —

# 내 앱이 바깥 AI에게 일을 부탁하는 한 줄
# (이미지를 보내면, AI가 재료 이름을 돌려준다)
result = api.ask(image="냉장고.jpg")

API 키(에이피아이 키)

한 문장 뜻 — 그 창구를 쓸 수 있게 해 주는 나만의 비밀번호. 누가 얼마나 썼는지를 이걸로 가린다.

일상비유 — 헬스장 회원 카드. 카드를 찍어야 문이 열리고, 그 카드로 들어간 기록이 내 앞으로 남는다. 남에게 빌려주면 남이 내 이름으로 쓴다.

한 줄 예 —

# 이 비밀번호가 있어야 창구가 열린다 (절대 공개 금지)
key = "AIzaSy...내_비밀_키"

멀티모달(multimodal)

한 문장 뜻 — 글뿐 아니라 그림·소리 같은 여러 형태의 입력을 함께 알아듣는 능력.

일상비유 — 눈도 있고 귀도 있는 사람. 글만 읽는 게 아니라, 사진을 보여 주면 "아, 이건 당근이네" 하고 알아본다.

한 줄 예 —

# 글이 아니라 '사진'을 입력으로 받는다
# → AI가 사진 속 재료를 글로 적어 준다
result = api.ask(image="냉장고.jpg")  # 사진 입력

(귀납 도입) 클로드 코드만으로는 냉장고 사진을 못 알아본다

5장까지 따라오면 이런 생각이 든다.

"클로드 코드가 코드도 짜 주는데, 냉장고 사진 보고 재료도 알아맞히겠지?"

그래서 시켜 본다.

# 클로드 코드에게 그냥 부탁만 한다
# "이 냉장고 사진 보고 재료 목록 만들어 줘"

그런데 막힌다.

클로드 코드는 내 컴퓨터 안의 글과 코드를 다룬다.

방금 찍은 사진을 실시간으로 눈으로 보고 재료를 골라내는 일은, 그 일에 특화된 바깥 서비스가 훨씬 잘한다.

마치 글은 내가 잘 쓰지만, 사진 속 물건을 알아보는 건 따로 눈 좋은 친구에게 맡기는 게 나은 것과 같다.

그 눈 좋은 친구를 빌려 오는 통로가 바로 API다.

API를 쓰면, 내 앱이 구글의 이미지 인식 같은 바깥 기능을 내 기능처럼 갖다 쓸 수 있다.

그래서 이 장은 "내 앱에 바깥 세상을 연결하는 법"을 배운다.

이 장에서 딱 4가지만

이 장에서 딱 4가지만

1. API — 내 앱이 바깥 서비스에게 일을 부탁하는 창구다. 웨이터라고 생각하면 된다.
2. API 키 — 그 창구를 여는 나만의 비밀번호다. 절대 남에게 보이면 안 된다.
3. 모델 고르기 — 일에 맞는 AI를 고른다. 사진을 잘 보는 AI, 글을 잘 쓰는 AI가 따로 있다.
4. PRD로 단계 쪼개기 — 냉장고 앱을 한 번에 안 만든다. 사진 인식 → 레시피 → 저장, 세 토막으로 나눠 시킨다.

개념 1 — API는 바깥 기능을 빌려 오는 창구

막히는 장면

"이미지 인식, 번역, 날씨 정보… 이런 걸 내가 다 만들어야 하나?" 싶어 막막한 적 있죠?

다 만들 필요 없다.

남이 이미 잘 만들어 둔 기능을, 정해진 창구로 빌려 쓰면 된다.

그 창구가 API다.

일상비유

식당에 가면 주방에 직접 들어가지 않는다.

웨이터에게 "스테이크 미디엄으로요" 하고 부탁한다.

웨이터가 주방에 전하고, 다 된 음식을 가져다준다.

내 앱(손님)이 바깥 서비스(주방)에 직접 못 들어가니, API(웨이터)에게 부탁하는 것이다.

한 문장 정의 — API는 내 앱이 바깥 서비스에게 정해진 방식으로 일을 부탁하고 결과를 받는 창구다.

예시 폭격

예 1 — 완성 예(눈으로만 보기).

# 내 앱이 바깥 날씨 서비스에게 부탁하는 한 줄
# "서울 날씨 알려 줘" → "맑음, 23도"가 돌아온다
weather = api.ask("서울 오늘 날씨")
print(weather)   # 맑음, 23도

예 2 — 부분 완성(빈칸 채우기). 냉장고 앱이라면 무엇을 부탁할까?

# 빈칸: 내 앱이 AI에게 부탁할 말을 적어 보자
# (정답 예시는 아래 줄에)
food = api.ask("___________")
# → 예: "이 사진에 있는 재료를 목록으로 알려 줘"

예 3 — 잘못된 예 vs 올바른 예(before/after).

# before — 부탁이 모호하다
api.ask("뭔가 해 줘")          # AI가 뭘 할지 모름

# after — 부탁이 또렷하다
api.ask("재료로 만들 요리 3개 추천해 줘")  # 원하는 결과가 옴

이럴 때 이렇게 — 만들고 싶은 기능이 "이미 세상에 있을 법한 것"(번역·이미지 인식·지도)이면, 직접 만들지 말고 "이거 API 있어?"부터 물어본다.

개념 2 — API 키는 나만의 비밀번호

막히는 장면

"창구가 그냥 열려 있으면 아무나 막 쓰겠네? 비용은 누가 내?" 하고 걱정한 적 있죠?

그래서 창구마다 비밀번호가 걸려 있다.

그 비밀번호가 API 키다. 내 키로 들어가면 그 사용량이 내 앞으로 기록된다.

일상비유

헬스장 회원 카드와 같다.

카드를 찍어야 문이 열리고, 들어간 기록이 내 이름으로 남는다.

카드를 남에게 빌려주면, 남이 내 이름으로 운동하고 내가 회비를 문다.

한 문장 정의 — API 키는 내가 그 창구를 쓸 수 있게 해 주는 나만의 비밀번호이며, 사용 기록과 비용이 이 키를 따라 나에게 붙는다.

예시 폭격

예 1 — 완성 예(키 발급 순서, 눈으로만).

# Google AI Studio에서 키 받는 흐름 (글로 옮긴 것)
# 1) aistudio.google.com 접속
# 2) [Get API key] 누르기
# 3) [Create API key]로 키 생성
# 4) 생긴 키를 안전한 곳에 복사 (다시 못 보는 경우 많음)

예 2 — 잘못된 예 vs 올바른 예(before/after).

# before — 키를 코드에 그대로 박아 인터넷에 올림 (위험!)
key = "AIzaSy_진짜_내_키_1234"   # 깃허브에 올라가면 누구나 봄

# after — 키를 코드 밖 비밀 자리에 두고 불러옴
key = 비밀상자에서_꺼내기("MY_API_KEY")  # 코드엔 키가 안 보임

예 3 — 부분 완성(빈칸). 키가 새면 가장 먼저 할 일은?

# 빈칸: 키가 유출됐을 때 해야 할 일
# (정답 예시는 아래 줄에)
# 1) ______________
# → 예: 그 키를 즉시 폐기(삭제)하고 새 키를 다시 발급

이럴 때 이렇게 — 키는 비밀번호다. 화면 공유·블로그·깃허브에 키가 보이는 코드를 올리지 않는다. 실수로 올렸다면, 그 키를 바로 폐기하고 새로 만든다.

개념 3 — 일에 맞는 AI 모델 고르기

막히는 장면

"AI면 다 똑같은 거 아냐? 아무거나 쓰면 안 되나?" 싶은 적 있죠?

AI마다 잘하는 일이 다르다.

사진을 잘 보는 AI, 글을 잘 쓰는 AI, 코드를 잘 짜는 AI가 따로 있다.

일에 맞는 AI를 고르는 게 첫 단추다.

일상비유

병원에 가도 과가 나뉘어 있다.

눈이 아프면 안과, 이가 아프면 치과로 간다.

내과 의사에게 충치를 보여 줘도 잘 못 고친다.

AI도 마찬가지로, 일에 맞는 곳을 찾아가야 한다.

한 문장 정의 — AI 모델은 저마다 강점이 달라, 하려는 일(사진 인식·글쓰기·코드 등)에 맞는 모델을 골라 연결한다.

세 가지 대표 모델을 표로 본다.

예시 폭격

예 1 — 완성 예. 냉장고 앱은 사진을 본다. 그래서 Gemini를 고른다.

# 사진을 봐야 하니 사진 잘 보는 모델을 고른다
model = "Gemini"   # 멀티모달(그림+글) 강점

예 2 — 잘못된 예 vs 올바른 예(before/after).

# before — 일과 안 맞는 모델
# 냉장고 '사진'을 보여 줘야 하는데 글만 받는 모델 선택 → 사진을 못 봄

# after — 일과 맞는 모델
# 그림을 알아보는 멀티모달 모델 선택 → 사진 속 재료를 읽어 냄

예 3 — 부분 완성(빈칸). 코드를 짜 달라고 할 땐 어느 모델이 어울릴까?

# 빈칸: 코드 작성에 어울리는 모델
# (정답 예시는 아래 줄에)
model = "______"
# → 예: Claude (코드 특화·꼼꼼함)

이럴 때 이렇게 — "내 일이 그림 보기냐, 글쓰기냐, 코드 짜기냐"를 먼저 정한다. 그다음 그 일을 잘하는 모델로 연결한다.

개념 4 — PRD로 단계 쪼개 앱 만들기

막히는 장면

"냉장고 앱 통째로 만들어 줘"라고 한 번에 시켰더니, 어디가 어딘지 뒤죽박죽 된 적 있죠?

큰 앱을 한 덩어리로 시키면 확인도 수정도 어렵다.

(이건 0장 척추 3 "한 번에 말고, 단계로 쪼개기"와 같은 이야기다.)

먼저 무엇을 만들지 한 장으로 정리(PRD)하고, 작은 단계로 쪼개 하나씩 시킨다.

일상비유

요리도 레시피(PRD)를 먼저 본다.

"① 재료 손질 → ② 볶기 → ③ 담기" 순서를 정해 두고, 한 단계씩 한다.

순서를 안 정하고 한꺼번에 하면 태우거나 빠뜨린다.

한 문장 정의 — PRD는 무엇을 왜 만들지 적은 한 장짜리 기획서이며, 그걸 작은 단계로 쪼개 하나씩 시키면 앱을 안전하게 완성한다.

냉장고 앱의 PRD는 세 단계로 쪼갠다.

예시 폭격

예 1 — 완성 예(1단계). 사진을 보내고 재료를 받는다.

# 1단계: 사진 → 재료 목록
재료 = api.ask(image="냉장고.jpg", 부탁="재료를 목록으로 알려 줘")
print(재료)   # ["당근", "계란", "우유", "파"]

예 2 — 부분 완성(빈칸, 2단계). 받은 재료로 무엇을 부탁할까?

# 2단계: 재료 → 레시피 (빈칸을 채워 보자)
레시피 = api.ask(부탁="___________", 재료=재료)
# → 예: "이 재료로 만들 수 있는 요리 3개 추천해 줘"

예 3 — 독립 적용(3단계). 마음에 든 레시피를 내 컴퓨터에 기억시키는 단계다.

# 3단계: 고른 레시피를 저장 (다음에 또 보기 위해)
# localStorage = 브라우저에 작게 적어 두는 메모지
저장("즐겨찾기", "당근 계란볶음")
# 앱을 껐다 켜도 그대로 남아 있다

이럴 때 이렇게 — 앱을 만들 땐, 먼저 "어떤 기능들이 필요하지?"를 번호 매긴 목록으로 적는다. 그게 PRD다. 그다음 1번부터 하나씩 시키고, 잘 되는지 보고, 다음으로 넘어간다.

완성된 냉장고 앱 한눈에 보기

세 단계를 다 잇고 나면, 이런 앱이 된다.

[ 냉장고를 부탁해 ]

[ 냉장고 사진 올리기 ]   ← 1단계 입력

인식된 재료:
당근  계란  우유  파      ← 1단계 결과 (멀티모달 API)

추천 레시피:
1. 당근 계란볶음 (15분)   ← 2단계 결과 (글쓰기 API)
2. 파전 (20분)
3. 우유 스크램블 (10분)

[ 저장 ]  [ 다른 레시피 ]   ← 3단계 (저장)

흐름을 한 줄로 요약하면 이렇다.

# 사진 → (멀티모달) 재료 → (글쓰기) 레시피 → (저장) 즐겨찾기
재료   = api.ask(image="냉장고.jpg")     # 1단계
레시피 = api.ask(부탁="요리 추천", 재료=재료)  # 2단계
저장("즐겨찾기", 레시피[0])              # 3단계

단순 규칙 (지금은 이 4개만)

지금은 다음 4개만 들고 가면 된다.

1. 바깥 기능이 필요하면 → "이거 API 있어?"부터 묻는다.
2. API 키는 비밀번호다 → 코드에 박거나 인터넷에 올리지 않는다.
3. 일에 맞는 모델을 고른다 → 사진은 사진 잘 보는 모델, 코드는 코드 잘 짜는 모델.
4. 한 번에 안 만든다 → PRD로 단계를 쪼개 하나씩 시키고 확인한다.

한 걸음 더 ▸ (지금 몰라도 됨)

"API를 쓰면 돈이 나가나?"가 궁금할 수 있다.

키로 들어간 만큼 사용료가 붙는 서비스가 많다. 처음엔 대개 무료 한도가 있으니, 연습 단계에선 거의 부담이 없다.

지금은 "키 = 비밀번호 = 내 앞으로 기록"만 기억하면 충분하다. 비용 관리는 익숙해진 뒤 천천히 챙기면 된다.

정리

이 장의 핵심 3줄.

API는 내 앱이 바깥의 똑똑한 기능을 빌려 오는 창구다(웨이터).

그 창구를 여는 비밀번호가 API 키이고, 일에 맞는 모델을 골라 연결한다.

큰 앱은 PRD로 적고 단계를 쪼개, 사진 인식 → 레시피 → 저장 순으로 하나씩 시켜 완성한다.

다음 장 예고 — 한 명의 AI 대신 여러 AI에게 역할을 나눠 맡기는 법을 본다. (지금 몰라도 됩니다 — 다음 장에서 천천히 풀려요.)